Amiga Plus 2000 #5

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Plus 2000 #5 / Amiga Plus CD - 2000 - No. 5.iso / Tools / DFUE / Spitfire² / developer / spitfireAPI.doc < prev next >

Wrap

Text File | 2000-01-01 | 13.8 KB | 757 lines

TABLE OF CONTENTS spitfireAPI.library/---overview--- spitfireAPI.library/Spit_AddUser spitfireAPI.library/Spit_CloseUsersFile spitfireAPI.library/Spit_FirstUser spitfireAPI.library/Spit_GetActiveUser spitfireAPI.library/Spit_GetClientSig spitfireAPI.library/Spit_GetEnvPath spitfireAPI.library/Spit_GetNotifyEvent spitfireAPI.library/Spit_GetNotifySig spitfireAPI.library/Spit_GetSystemID spitfireAPI.library/Spit_GetUserID spitfireAPI.library/Spit_GetUserName spitfireAPI.library/Spit_GetUserPassword spitfireAPI.library/Spit_GetUserPath spitfireAPI.library/Spit_GetUserPos spitfireAPI.library/Spit_GotoUser spitfireAPI.library/Spit_LastUser spitfireAPI.library/Spit_NextUser spitfireAPI.library/Spit_NotifyClients spitfireAPI.library/Spit_NotifyServer spitfireAPI.library/Spit_NumberUsers spitfireAPI.library/Spit_OpenUsersFile spitfireAPI.library/Spit_PrevUser spitfireAPI.library/Spit_ReadEvent spitfireAPI.library/Spit_RegisterClient spitfireAPI.library/Spit_RegisterServer spitfireAPI.library/Spit_RemoveClient spitfireAPI.library/Spit_RemoveServer spitfireAPI.library/Spit_SaveUsersFile spitfireAPI.library/Spit_SetActiveUser spitfireAPI.library/Spit_SetEnvPath spitfireAPI.library/Spit_SetSystemID spitfireAPI.library/Spit_SetUserID spitfireAPI.library/Spit_SetUserName spitfireAPI.library/Spit_SetUserPassword spitfireAPI.library/Spit_SetUserPath spitfireAPI.library/Spit_Wait4Event spitfireAPI.library/---overview--- spitfireAPI.library/---overview--- SPITFIRE² DESKTOP CLIENTS Spitfire² clients need to communicate with the HSM program. This is done through the spitfireAPI.library. The client needs to call Spit_RegisterClient() in order to receive messages from HSM. When existing, the client needs to remove itself with a call to Spit_RemoveClient(). A client may look like this: client = Spit_RegisterClient(); ... Spit_WaitForEvent(client); Spit_ReadEvent(client,&event,&data); ... Spit_RemoveClient(client); More often though, you will want to listen to other ports as well, for instance that of a window: client = Spit_RegisterClient(); ... mask = (1<<Spit_GetClientSig(client))|(1<<windowsigbit); Wait(mask); Spit_ReadEvent(client,&event,&data); ... Spit_RemoveClient(client); EVENT CODES HSM broadcasts the following event codes: SPIT_QUIT If your client receives SPIT_QUIT, remove it as soon as possible. SPIT_SHOWINTERFACE When this message is broadcast, the client should open its window. SPIT_HIDEINTERFACE When this message is broadcast, the client should close its window and anything similar. SPIT_SAVEDB A broadcase of this message means that HSM is in HotSync mode, and your application should save all data in order for the conduit to synchronize the data. SPIT_LOADDB This event is usually broadcast once HotSyncing is done, thus your application should reload and update its data. SPIT_NEWUSERS This event indicates a new user has been added to the user list. You should update your applications user list as soon as possible. spitfireAPI.library/Spit_AddUser spitfireAPI.library/Spit_AddUser NAME Spit_AddUser -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_CloseUsersFile spitfireAPI.library/Spit_CloseUsersFile NAME Spit_CloseUsersFile -- ends access to an opened users.dat file SYNOPSIS success = Spit_CloseUserFile(userlist) D0 D0 LONG Spit_CloseUser(APTR); FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_FirstUser spitfireAPI.library/Spit_FirstUser NAME Spit_FirstUser -- SYNOPSIS = Spit_FirstUser(userlist) FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_GetActiveUser spitfireAPI.library/Spit_GetActiveUser NAME Spit_GetActiveUser -- SYNOPSIS = Spit_GetActiveUser(userlist) FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_GetClientSig spitfireAPI.library/Spit_GetClientSig NAME Spit_GetClientSig -- get the signal of a client port SYNOPSIS signal = Spit_GetClientSig(client) D0 D0 UBYTE Spit_GetClientSig(APTR); FUNCTION This function returns the signal that will be set when a message arrives at the given client's message port. Using a Wait() for this signal is somewhat more useful than using Spit_WaitForEvent(), as this will let you listen to other signals as well. INPUTS client - a pointer to the client whose signal you wish to obtain. RESULT signal - the number of the signal associated with the given client's port. SEE ALSO Spit_ReadEvent(), Spit_WaitForEvent() spitfireAPI.library/Spit_GetEnvPath spitfireAPI.library/Spit_GetEnvPath NAME Spit_GetEnvPath -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_GetNotifyEvent spitfireAPI.library/Spit_GetNotifyEvent NAME Spit_GetNotifyEvent -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_GetNotifySig spitfireAPI.library/Spit_GetNotifySig NAME Spit_GetNotifySig -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_GetSystemID spitfireAPI.library/Spit_GetSystemID NAME Spit_GetSystemID -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_GetUserID spitfireAPI.library/Spit_GetUserID NAME Spit_GetUserID -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_GetUserName spitfireAPI.library/Spit_GetUserName NAME Spit_GetUserName -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_GetUserPassword spitfireAPI.library/Spit_GetUserPassword NAME Spit_GetUserPassword -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_GetUserPath spitfireAPI.library/Spit_GetUserPath NAME Spit_GetUserPath -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_GetUserPos spitfireAPI.library/Spit_GetUserPos NAME Spit_GetUserPos -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_GotoUser spitfireAPI.library/Spit_GotoUser NAME Spit_GotoUser -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_LastUser spitfireAPI.library/Spit_LastUser NAME Spit_LastUser -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_NextUser spitfireAPI.library/Spit_NextUser NAME Spit_NextUser -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_NotifyClients spitfireAPI.library/Spit_NotifyClients NAME Spit_NotifyClients -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_NotifyServer spitfireAPI.library/Spit_NotifyServer NAME Spit_NotifyServer -- notify the HSM server of an event SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_NumberUsers spitfireAPI.library/Spit_NumberUsers NAME Spit_NumberUsers -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_OpenUsersFile spitfireAPI.library/Spit_OpenUsersFile NAME Spit_OpenUsersFile -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_PrevUser spitfireAPI.library/Spit_PrevUser NAME Spit_PrevUser -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_ReadEvent spitfireAPI.library/Spit_ReadEvent NAME Spit_ReadEvent -- receive a message from the server SYNOPSIS success = Spit_ReadEvent(client,event,data) D0 A0 D1 D0 ULONG Spit_ReadEvent(APTR,ULONG *,ULONG *); FUNCTION This function reads a message from the client's message port. If a message exists, it will copy the event and data codes into the addresses provided by the caller, and dispose of the message. You should keep calling this function until it returns FALSE, as several messages might arrive at the port simultaneously. INPUTS client - the client whose port to check. event - pointer to a longword in which to store the event code of the message, if there is one. data - ditto for the data code. RESULT success - TRUE if there was a message, in which case the longwords pointed to by the event and data fields will contain the info broadcast by the message, FALSE if there was no message. SEE ALSO spitfireAPI.library/Spit_RegisterClient spitfireAPI.library/Spit_RegisterClient NAME Spit_RegisterClient -- create a Spitfire² message client SYNOPSIS client = Spit_RegisterClient() D0 APTR Spit_RegisterClient(void); FUNCTION This function creates a client of with the HSM message server. A Spitfire² client should call this in order to receive messages from the HSM through the Spit_ReadEvent() call. The message server must be active before any clients can be created. If it is not, this function will fail. Normally, clients will be launched by the DAM after the HSM server has been created, so this should not be a problem. RESULT client - a pointer to a Spitfire² message client structure, or FALSE if the client could not be created. SEE ALSO Spit_RemoveClient(), Spit_ReadEvent() spitfireAPI.library/Spit_RegisterServer spitfireAPI.library/Spit_RegisterServer NAME Spit_RegisterServer -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_RemoveClient spitfireAPI.library/Spit_RemoveClient NAME Spit_RemoveClient -- destroy a KRSNAke message client SYNOPSIS success = Spit_RemoveClient(client) D0 D0 ULONG Spit_RemoveClient(APTR); FUNCTION This function detaches a client from the server and destroys it. All clients created by the Spit_RegisterClient() function must be disposed of with this function. INPUTS client - a pointer to a client returned from the Spit_RegisterClient() function. RESULT success - TRUE if the client was removed, FALSE otherwise. SEE ALSO Spit_RegisterClient() spitfireAPI.library/Spit_RemoveServer spitfireAPI.library/Spit_RemoveServer NAME Spit_RemoveServer -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_SaveUsersFile spitfireAPI.library/Spit_SaveUsersFile NAME Spit_SaveUsersFile -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_SetActiveUser spitfireAPI.library/Spit_SetActiveUser NAME Spit_SetActiveUser -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_SetEnvPath spitfireAPI.library/Spit_SetEnvPath NAME Spit_SetEnvPath -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_SetSystemID spitfireAPI.library/Spit_SetSystemID NAME Spit_SetSystemID -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_SetUserID spitfireAPI.library/Spit_SetUserID NAME Spit_SetUserID -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_SetUserName spitfireAPI.library/Spit_SetUserName NAME Spit_SetUserName -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_SetUserPassword spitfireAPI.library/Spit_SetUserPassword NAME Spit_SetUserPassword -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_SetUserPath spitfireAPI.library/Spit_SetUserPath NAME Spit_SetUserPath -- SYNOPSIS FUNCTION INPUTS RESULT SEE ALSO spitfireAPI.library/Spit_Wait4Event spitfireAPI.library/Spit_Wait4Event NAME Spit_WaitForEvent -- wait for a message to arrive at a client's port SYNOPSIS success = Spit_WaitForEvent(client) D0 D0 ULONG Spit_WaitForEvent(APTR); FUNCTION This function calls WaitPort() for the given client's port, which causes the calling task to wait until the client receives a message from the server. INPUTS client - the client whose port to wait on. RESULT success - TRUE if the wait succeeded, FALSE otherwise. At present, the FALSE return value only happens if you pass a NULL client pointer. SEE ALSO Spit_GetClientSig(), Spit_ReadEvent()